╩╩The MenuChange XCMD Installer will install the MenuChange XCMD into any file you choose, or it will create a new file into which it puts the XCMD. The remainder of these instructions describe the functions of the MenuChange XCMD.
╩╩This XCMD allows you to alter FoxBase menus. You may change FoxBase's normal menus (for what purpose, I can't imagine), but it is more useful in altering the user-installed menus that you create within your FoxBase programs. Using this XCMD is very easy and enormously more efficient than using the built-in FoxBase commands. You can now design your user interface without worrying about whether it will take FoxBase ten seconds to redraw altered menus. You also don't need to remember the entire state of your menu system just to change one item in the one menu.
╩╩If you don't understand this (or any other major point covered in these instructions) please don't try to use this XCMD. It will not be useful to you.
Ñ How to print these instructions
╩╩If you open this Application as a document in Microsoft Word (or any program or desk accessory capable of opening arbitrary documents) it will appear to be just these instructions. They can then be formatted and printed in whatever way you wish. In MS-Word, hold down the shift key while you select 'Open╔' from the 'File' menu. In McSink, hold down the Option key. (Don't try to save text into this program, though, or you'll break it!) Alternatively, you can change the Type of this file to 'TEXT' and open it with any word processor (but remember to change it back, or the program won't work).
Ñ How to use MenuChange XCMD
╩╩To use this (or any) XCMD with FoxBase, you must have a version of FoxBase dated no earlier than December 2, 1988. The XCMD must be in a resource file which has been opened by FoxBase. In practice, this means that it can be in the:
╩╩╩╩1) System File (not recommended)
╩╩╩╩2) FoxBase (or FoxRun) program file (not a great idea either)
╩╩╩╩3) FoxUser file (this is not bad)
╩╩╩╩4) file opened in FoxBase by the "Set Resource To╔" command
╩╩╩╩5) Procedure file, if you do a "Set Procedure To╔" command
Of these, the fifth option is the best for packaged applications, and the fourth is recommended for everything else (or packages under development).
╩╩Once an XCMD is in an open resource file, it must be loaded into memory by using the load command:
╩╩╩╩╩╩╩╩╩Load "MenuChange"
To use the XCMD, write:
╩╩╩╩╩╩╩╩╩Call "MenuChange" With {Command},{Parameters}
If you need to free the memory (or file) used by the XCMD, you write:
╩╩╩╩╩╩╩╩╩Release Module "MenuChange"
The string in quotes is the resource name of the XCMD, so if you rename it with ResEdit to "mh" (for brevity) you would say ╘Load "mh"╒. Resource names are not case-sensitive.
Ñ MenuChange commands
╩╩╩╩Call "MenuChange" With 1,{Menu #},{New Menu Title}
This will create a new menu BEFORE the menu number you specify. To append a menu to the menu bar, you may use 0 or any number larger than the number of user menus.
╩╩╩╩Call "MenuChange" With 2,{Menu #}
This will delete the indicated menu. It is safe to delete user-installed menus created from within FoxBase.
╩╩╩╩Call "MenuChange" With 3,{Menu #},{New Menu Title}
This changes the title of the indicated Menu.
╩╩╩╩Call "MenuChange" With 4,{Menu #},{Item #},{New Item Name}
This changes the indicated item in the indicated menu to the new name. Characters which code for command keys and other special effects (as listed in Inside Mac) are NOT recognized -- that's what the rest of these commands are for.
╩╩╩╩Call "MenuChange" With 5,{Menu #},{Item #},{New Item CmdKey}
This changes the indicated command key equivalent. The new key should be one character, or "" (empty quotes) to remove the current command key.
╩╩╩╩Call "MenuChange" With 6,{Menu #},{Item #},{New Item Mark}
This changes the indicated mark (on the left of a menu item, such as a check mark). The new mark should be one character, or "" (empty quotes) to remove the current mark. (By the way, "Chr(18)" is a check mark, so you can use this to check items.)
╩╩╩╩Call "MenuChange" With 7,{Menu #},{Item #},{Style}
This changes the Font Style of a menu item. The style can be any combination of the letters B,I,U,O,S,C, and E, which mean Bold, Italic, Underline, Outline, Shadow, Condensed, and Extended. Lowercase letters may be used. Use the empty string ("") to make a menu item plain.
╩╩╩╩Call "MenuChange" With 8,{Menu #},{Item #},{New Icon #}
This changes the icon associated with a menu item. Use the numbers 1 through 255 to put an icon in front of a menu item, or 0 for no icon. The icon displayed is the icon numbered [256+the number you used]. The icon must be in an open resource file, just like the XCMD (though not necessarily the same one).
╩╩╩╩Call "MenuChange" With 9,{Menu #},{Item #},{New Item Name}
This creates a new menu item in the (already existing) menu specified. The new item's name will be parsed as specified in Inside Mac (or the new FoxBase Command Reference, page 2-127). For example, an item named "Find/F" will create a new item named "Find" which has a command-key equivalent "F".
╩╩The item number is actually the item number BEFORE the item you are inserting. To create an item at the top of the menu, you use item 0. To put a new item at the bottom of the menu, use any number larger than the number of items already there (99 will work well).
╩╩╩╩Call "MenuChange" With 0,{Menu #},{Item #}
This deletes the specified menu item. You can delete menus created both by the MenuChange XCMD and by the FoxBase "Menu" command.
Ñ Parameters- Menu and Item numbers
╩╩Menu numbers are numbered the same as in FoxBase- menu #1 is the first user-installed menu. The "Edit" menu is menu #0, "File" is #-1, and the Apple menu is #-2. This means that you have access to Fox's own menus, but it does NOT mean that altering them is a good idea. Do so at your own risk. It is an error to use a menu number lower than -2 or higher than the number of user menus installed (actually, the total number of menus minus 3, which is the same thing unless you are mucking about with Fox's own menus).
╩╩Items are numbered from 1 to the number of items in the menu. With the exception of command #9 (insert an item), it is an error to specify a menu items outside of this range.
Ñ Error Handling
╩╩This XCMD will reject any bad parameters passed to it, and display an alert dialog explaining why it had a problem. It should never crash. However, if future versions of FoxBase have more or less than three FoxBase menus before user menus (not terribly likely, I think) that could cause problems.
╩╩If you get an alert saying "Fatal Error #{whatever}", this indicates a disk error. It is NOT a bug in the Installer.
╩╩I have not attempted to test this XCMD with HyperCard. I have no idea why anyone would want to use it with HyperCard, or what the results would be. However, it should work with HyperCard or any program that fully supports the HyperCard XCMD interface.
Ñ Technical notes
╩╩This XCMD is a single resource and can be safely installed and removed using ResEdit or any other resource-moving program.
╩╩The Installer will overwrite any already-existing XCMD named "MenuChange". This is good for replacing an older (or damaged) one. It will NEVER delete or replace any other resources, or entire files.
╩╩The alert resource used for error messages is actually one of the alerts normally found in the FoxUser file. If that file is not available, and the resources can't be found elsewhere, you won't get any alert.
╩╩Commands #1 and 2, Insert and Delete Menus, appear to be perfectly safe under the current version of FoxBase (all versions through 1/1/89). You may delete menus created with the FoxBase "Menu" command, and you may use the "Menu Bar" command to delete menus created by this XCMD. I expect both of these commands to continue working in the future, but it is just barely possible that some future version of FoxBase might break them.
╩╩To alter the Menu Title (command #3) I have to play a bit with the Menu Record. This is fairly kosher according to Inside Mac Volume 5, but there is a faint possibility that this will break under a new system or ROM release.
╩╩All of the other commands are 100% OK by Inside Mac, and should continue to work indefinitely. They use the standard routines defined in Inside Mac Volumes 1 through 5. All of this works because FoxBase simply doesn't care what the user menus look like, and it blindly passes on whatever menu hits it sees so long as they don't fall within FoxBase's private menu range.
Ñ Revision History
╩╩This is the first released version.
Ñ Credits
╩╩Without Think's Lightspeed Pascal, this would have been written in assembler. It might have been available by 1990.
╩╩Without Fox Software's FoxBase+/Mac, I might still be using Omnis or 4D. I might be insane by 1990...
